Desktop Key Mapper Tutorial
===========================

Double click the module and you should get a new Wimp Module Task on the
Task Manager display. There will also be a module "DesktopKeyMap" listed
with *Modules. If one of these is stopped, the other one will stop too.

The command *DesktopKeyMap_List will output for example:

   *DesktopKeyMap_List
   TASK NAME                        ON  KEY MAP APPLIED
   *

This example shows that no key mappings are loaded.

Next, create a mapping file in your favourite text editor.
The format is:

a) Comment lines start with a #
b) Non numerical values indicate the character to map from
c) This is followed by a space or tab, followed by the character to map to
d) Numerical values can also be used to indicate the character to map
   and can be decimal (eg 32) or hexadecimal (eg 0x20) 
e) If there is no 'to' character the 'from' character is disabled 
f) Any characters you wish to remain unaffected should not be included

The following example:

#comment
A B
B A#comment2
C #blah
D D
32 160
0x1cd 0x1ce
69 e

begins with a comment, maps A to B and B to A, disables C, remaps D to
D, maps soft space to hard space, Wimp key &1CD to &1CE and capital E to
lower case e.

To load a mapping, issue the command

*DesktopKeyMap_Load <mapping file pathname> ["<task name>"] [NumLock]

eg. *DesktopKeyMap_Load test1 "Edit"

The taskname MUST be in quotes "" since it may contain spaces. Spacing
and capitalsation is important. If no taskname is specified then all
loaded applications will be affected by the keymap.

The command *DesktopKeyMap_List will output:

   *DesktopKeyMap_List
   TASK NAME                        ON  KEY MAP APPLIED
   Edit                             N   test1
   *

To activate, simply load Edit, the ON field will now show Y. Only the
first instantiation of a program will be filtered.

Now, open an !Edit window and test the filter by typing 'ABCDE' and the
output will be 'BADe'. Load another copy of Edit at the same time and
the keypresses are NOT filtered in the second copy.

The CtrlF12 file should be loaded as:

*DesktopKeyMap_Load CtrlF12 "Task Manager"

Then load Writer or whatever and issue a

*DesktopKeyMap_Load RussianMap "Writer+" NumLock

(or "Writer Plus", I don't know RISC OS 5), change the font used by
Writer to your Russian font and start typing. The filter will only be
active now with the keyboard NumLock on.

Remove a filter by quitting from the Task Manager window menu, or issuing

*DesktopKeyMap_Remove ["<task name>"]

Again, no task name = all tasks. Be careful with a global keymap and a
task-specific keymap cancelling each other out.
